/*
 * Copyright (c) 2001, 2002 Boris Pruessmann and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Common Public License v0.5
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v05.html
 * 
 * Contributors:
 *    Boris Pruessmann - Initial implementation.
 */
package net.sourceforge.perforce.core.api;

import java.util.Properties;

import net.sourceforge.perforce.core.PerforceCorePlugin;
import net.sourceforge.perforce.core.PerforceException;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.QualifiedName;

/** This interface describes the public API of the ServerManager which is used to manage
  * perforce servers known to the plugin.
  * 
  * @version $Revision: 67 $
  * @author  <a href="mailto:bpruessmann@users.sourceforge.net">Boris Pruessmann</a>
  */
public interface IPerforceServerManager 
{
	// ----------------------------------------------------------------------------------- Constants
	
	/** Name of the persistent property used to attach a server to a project. */
	QualifiedName QN_PERSISTENT_SERVER = new QualifiedName(PerforceCorePlugin.ID, "server");
	
	// ------------------------------------------------------------------------------------- Methods
	
	/** Call this method to create a new PerforceServer. The server is not added to the control
	  * of the server manager. Checks whether there is already a server object with the same
	  * (calculated) unique name.
	  * 
	  * @param properties containing connection data.
	  * @return the new perforce server.
	  * 
	  * @throws PerforceException in case of an error.
	  */
	IPerforceServer createPerforceServer(Properties properties)
		throws PerforceException;
	
	/** Adds the given server object to the control of the manager.
	  * 
	  * @param server to be added.
	  * 
	  * @throws PerforceException in case of an unexpected error.
	  */
	void addPerforceServer(IPerforceServer server)
		throws PerforceException;
	
	/** Call this method to get an array of registered perforce servers.
	  * 
	  * @return array of servers.
	  */
	IPerforceServer[] getPerforceServers();

	/** Call this method to retrieve a properties object containing the system defaults
	  * for the information needed to create a server object.
	  * 
	  * @return proeprties containing defaults.
	  */
	Properties getConnectionDefaults();
	
	/** Associates the given project and server.
	  * 
	  * @param project the project to be associated.
	  * @param server the perforce server.
	  * @param monitor used for progress feedback.
	  * 
	  * @throws PerforceException in case of an error.
	  */
	void setSharing(IProject project, IPerforceServer server, IProgressMonitor monitor)
		throws PerforceException;

	/** Call this to retrieve the PerforceServer that is (potentially) responsible for the
	  * given resource.
	  * 
	  * @param resource the resource.
	  * @return the responsible server or null.
	  * 
	  * @throws PerforceException in case of an error.
	  */
	IPerforceServer getPerforceServer(IResource resource)
		throws PerforceException;

	/** Returns a list of projects that reference the given server.
	  * 
	  * @param server the server.
	  * @return array of referencing projects.
	  * 
	  * @throws PerforceException in case of an error.
	  */
	IProject[] getReferencingProjects(IPerforceServer server)
		throws PerforceException;

	/** Addes the given listener to the notification list.
	  * 
	  * @param listener the listener.
	  */
	void addPerforceListener(IPerforceListener listener);

	/** Removes the given listener from the notification list.
	  *
	  * @param listener the listener.
	  */
	void removePerforceListener(IPerforceListener listener);
}
